---
title: "Reference: Workflows API | Client SDK"
description: Learn how to interact with and execute automated workflows in Mastra using the client-js SDK.
---

# Workflows API

The Workflows API provides methods to interact with and execute automated workflows in Mastra.

## Getting All Workflows

Retrieve a list of all available workflows:

```typescript
const workflows = await mastraClient.listWorkflows();
```

## Working with a Specific Workflow

Get an instance of a specific workflow by its ID:

```typescript title="src/mastra/workflows/test-workflow.ts"
export const testWorkflow = createWorkflow({
  id: "city-workflow",
});
```

```typescript
const workflow = mastraClient.getWorkflow("city-workflow");
```

## Workflow Methods

### details()

Retrieve detailed information about a workflow:

```typescript
const details = await workflow.details();
```

### createRun()

Create a new workflow run instance:

```typescript
const run = await workflow.createRun();

// Or with an existing runId
const run = await workflow.createRun({ runId: "existing-run-id" });
```

### startAsync()

Start a workflow run and await the full result:

```typescript
const run = await workflow.createRun();

const result = await run.startAsync({
  inputData: {
    city: "New York",
  },
});
```

You can also pass `initialState` to set the starting values for the workflow's state:

```typescript
const result = await run.startAsync({
  inputData: {
    city: "New York",
  },
  initialState: {
    count: 0,
    items: [],
  },
});
```

The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](/docs/v1/workflows/workflow-state) for more details.

### start()

Start a workflow run without waiting for completion:

```typescript
const run = await workflow.createRun();

await run.start({
  inputData: {
    city: "New York",
  },
});

// Poll for results later
const result = await workflow.runExecutionResult(run.runId);
```

This is useful for long-running workflows where you want to start execution and check results later.

### resumeAsync()

Resume a suspended workflow step and await the full result:

```typescript
const run = await workflow.createRun({ runId: prevRunId });

const result = await run.resumeAsync({
  step: "step-id",
  resumeData: { key: "value" },
});
```

### resume()

Resume a suspended workflow step without waiting for completion:

```typescript
const run = await workflow.createRun({ runId: prevRunId });

await run.resume({
  step: "step-id",
  resumeData: { key: "value" },
});
```

### stream()

Stream workflow execution for real-time updates:

```typescript
const run = await workflow.createRun();

const stream = await run.stream({
  inputData: {
    city: "New York",
  },
});

for await (const chunk of stream) {
  console.log(JSON.stringify(chunk, null, 2));
}
```

### runExecutionResult()

Get the execution result for a workflow run:

```typescript
const result = await workflow.runExecutionResult(runId);
```

<h3>Run result format</h3>

A workflow run result yields the following:

<PropertiesTable
  content={[
    {
      name: "runId",
      type: "string",
      description: "Unique identifier for this workflow run instance",
    },
    {
      name: "eventTimestamp",
      type: "Date",
      description: "The timestamp of the event",
    },
    {
      name: "payload",
      type: "object",
      description: "Contains currentStep (id, status, output, payload) and workflowState (status, steps record)",
    },
  ]}
/>
